Skip to content

feat(messagepack): MessagePack value serializer package - #405

Open
cosmin-staicu wants to merge 1 commit into
perf/value-serializer-wiringfrom
perf/messagepack-serializer
Open

cosmin-staicu wants to merge 1 commit into
perf/value-serializer-wiringfrom
perf/messagepack-serializer

Conversation

@cosmin-staicu

@cosmin-staicu cosmin-staicu commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

Summary

Fourth in the fast value serializer stack, on top of #404. Adds the UiPath.Caching.MessagePack package: a value serializer that a policy picks with Serializer.Write = "messagepack".

services.AddCaching(...).AddMessagePackSerializer(name = "messagepack", configure)

MessagePackValueSerializerOptions
  CompressionThresholdBytes   1024    values at or above it are tried with LZ4 (0 tries every value)
  MaxDecompressedBytes        512 MiB a compressed value claiming more is rejected
  SerializerOptions           contractless resolver, MessagePackSecurity.UntrustedData
                              (supplied options carrying TrustedData are made untrusted)

write
  below threshold                    -> 0x02 plain
  at or above, LZ4 result smaller    -> 0x03 LZ4 block array
  at or above, not smaller           -> 0x02 plain
read
  0x02 / 0x03 by header; a value claiming more than 255x its stored size, or more than
  MaxDecompressedBytes, is rejected (also applied as MessagePack's own decompression limit)
  a value larger than MaxDecompressedBytes is written as 0x02, so it stays readable
  OutOfMemoryException wrapped by MessagePack is rethrown unwrapped

The serializer is internal and owns only ids 0x02 and 0x03. Library ids are registered through an internal method, so UiPath.Caching gives the package InternalsVisibleTo. The public AddValueSerializer keeps accepting consumer ids only. Because of that, the package depends on the exact same UiPath.Caching version ([3.2.0] in the nuspec).

Evidence

  • Through RedisCache with a fake connector, MessagePack against JSON (BenchmarkDotNet short run; times are noisy, allocations are exact):

    Size Stored bytes JSON / MessagePack Get JSON / MessagePack Get alloc Set JSON / MessagePack Set alloc
    Small 171 / 102 3.80 / 3.43 us 1120 / 560 B 0.83 / 0.64 us 776 / 424 B
    Medium 803 / 645 5.69 / 4.63 us 2152 / 1016 B 1.86 / 0.91 us 1408 / 968 B
    Large 388,800 / 280,700 2.04 / 1.32 ms 608,936 / 162,588 B 1.37 / 0.56 ms 390,686 / 281,940 B

    The fake connector now keeps its own copy of each value, so Set allocations include one stored-size copy for both formats. An earlier Large MessagePack read measured a miss on a reused pooled buffer; that number is gone.

  • Compression: MessagePack's built-in Lz4BlockArray was within noise of a plain-then-K4os wrapper and allocates far less on write, so no new dependency. Compressible values shrink about 2-3x, writes cost about 2-3x, reads about the same.

  • A value is serialized once. Below the threshold it is copied; at or above it, the plain bytes go through MessagePack's LZ4 block array and the smaller form is kept. Below the threshold this is 20% faster. Above it, short runs showed 0 to 12% slower (16 KB worst), inside those runs' noise.

  • Mutations caught: compressed value reported as 0x02, the "smaller" check dropped, labelling by length only, defaults without UntrustedData, supplied TrustedData kept, null written as zero bytes, a threshold of 0 passed through, the 255x ratio moved either way, no absolute cap, pooled arrays returned uncleared, a non-binary first block accepted, MessagePack's 64 MiB limit left in place, out-of-memory left wrapped.

  • End to end against Redis: a key written JSON, then MessagePack, then JSON reads correctly each time; hash cache, batch, multilayer invalidation and peer field updates with real MessagePack ids.

  • Full suite with Redis: 4948, 0 failed, 1 skipped. -c Release -warnaserror builds clean.

Merge Danger

Door: two-way

A new package. Nothing changes until an app registers it and a policy names it. Once values are written as MessagePack, every reader of those keys needs this package registered (readers first in a rolling deploy, as docs/how-to/extending.md says).

Blast Radius: storage

Only keys whose policy names the MessagePack serializer.

PackageValidationBaselineVersion is cleared in the new csproj because no baseline package exists yet. Set it after the first release.

@github-actions github-actions Bot added the needs-cla-review A maintainer should assess whether a signed CLA is required (see CONTRIBUTING.md) label Nov 12, 2026
@github-actions

Copy link
Copy Markdown

🔎 Maintainer heads-up: automated triage flagged this PR as potentially material, so it may need a signed CLA in addition to the DCO sign-off.

Strong signals

  • adds public API surface (PublicAPI.Unshipped.txt in src/UiPath.Caching.MessagePack)
  • changes shipped public API — possible removal/breaking change (PublicAPI.Shipped.txt in src/UiPath.Caching.MessagePack)
  • adds dependency: MessagePack
  • adds new project(s): src/UiPath.Caching.MessagePack/UiPath.Caching.MessagePack.csproj

This is advisory only — the bot does not decide. Please judge against the CLA criteria (material, product-critical, patent-sensitive, corporate contributor, broad commercial use). Note that thresholds can be gamed by splitting PRs, so use your judgement.

  • If a CLA is needed → add the cla-required label (a contributor comment with signing steps is posted automatically).
  • If it is not needed → replace needs-cla-review with cla-not-required so later pushes don't re-flag it.

@cosmin-staicu
cosmin-staicu force-pushed the perf/value-serializer-wiring branch from 9c17a18 to e368986 Compare November 13, 2026 13:39
@cosmin-staicu
cosmin-staicu force-pushed the perf/messagepack-serializer branch from 3abbcdb to 25ebdbf Compare November 13, 2026 13:39
@cosmin-staicu
cosmin-staicu force-pushed the perf/value-serializer-wiring branch 4 times, most recently from 9378c89 to f4a9d49 Compare November 14, 2026 03:46
@cosmin-staicu
cosmin-staicu force-pushed the perf/messagepack-serializer branch from 25ebdbf to 1e5409d Compare November 14, 2026 03:53
@cosmin-staicu
cosmin-staicu force-pushed the perf/value-serializer-wiring branch from f4a9d49 to a32ea16 Compare November 14, 2026 04:17
Adds the UiPath.Caching.MessagePack package, a value serializer that a policy picks with Serializer.Write = "messagepack". It is registered with AddMessagePackSerializer, which takes an optional name and a configure callback for MessagePackValueSerializerOptions.

Values below CompressionThresholdBytes (default 1024) are written plain with format id 0x02. At or above it the value is tried with LZ4, stored as id 0x03 when the result is smaller and as plain 0x02 otherwise. A threshold of 0 tries every value. Reads accept both ids and reject a compressed value that claims more than 255 times its stored size or more than MaxDecompressedBytes (default 512 MiB), which is also applied as MessagePack's own decompression limit. A value larger than that cap is written plain so it stays readable, and an OutOfMemoryException wrapped by MessagePack is rethrown unwrapped.

The default serializer options use a contractless resolver with MessagePackSecurity.UntrustedData, and supplied options that carry TrustedData are made untrusted. The serializer is internal and owns only ids 0x02 and 0x03, registered through an internal method that UiPath.Caching exposes to the package with InternalsVisibleTo. The public AddValueSerializer still accepts consumer ids only, so the package depends on the exact same UiPath.Caching version.

Nothing changes until an app registers the package and a policy names it. Once values are written as MessagePack, every reader of those keys needs the package registered, readers first in a rolling deploy.

Signed-off-by: Cosmin Staicu <cosmin.staicu@uipath.com>
@cosmin-staicu
cosmin-staicu force-pushed the perf/messagepack-serializer branch from 1e5409d to e77fc7f Compare November 14, 2026 04:35

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs-cla-review A maintainer should assess whether a signed CLA is required (see CONTRIBUTING.md)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant